Revision: arch--devo--1.0--patch-54
Archive: lord@regexps.com--2002
Creator: Tom Lord <lord@regexps.com>
Date: Mon Mar  4 02:07:13 PST 2002
Standard-date: 2002-03-04 10:07:13 GMT
Summary: coding standard and bug fixes to the new config commands
Keywords: 
New-files: {arch}/arch/arch--devo/arch--devo--1.0/lord@regexps.com--2002/patch-log/patch-54
Modified-files: ChangeLog
  ChangeLog.d/geisler@ece.nwu.edu--public/ChangeLog.geisler--1.0
  ChangeLog.d/geisler@ece.nwu.edu--src/ChangeLog.geisler--1.0
  ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord--1.0
  ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord-doc--1.0
  configurations/build-config.sh
  configurations/config-history.sh
  configurations/record-config.sh
  configurations/replay-config.sh
  configurations/show-config.sh
  configurations/update-config.sh
  naming-conventions/indicated-config-file.sh
  naming-conventions/valid-config-name.sh
New-patches: lord@regexps.com--2002/arch--devo--1.0--patch-54

[Comments on the previous patch set being fixed by this patch set]

A standard style for formatting opening comments and tag lines has
emerged.  The right stye is:

	# file-basename: brief description
	#
	################################################################
	# Copyright ...
	# 

There are exactly 64 "#" characters on that line in the middle and the 
line with the brief description should fit in 64 characters and be
first line in the file.

Don't forget to update the program name and description.  For example,
the error message near "--config-dir)" in `indicated-config-file' said
the error came from `valid-config-name'.

The old habit of using 0 and 1 for option variables (e.g. "exists=0")
is something I abandoned.  Instead, in _almost_ every case in new
code, the option should be used (e.g. "exists=--exists").  The right
way to test if an option is set is like:

	if test ! -z "$exists" ; then
	  ... --exists was specified ...
	fi

That convention means that you can forward an option to another
command in a relable way:

	larch some-other-command $exists ...

The implementation of "--force" in `valid-config-name' is wrong: it
only works if "--force" comes later on the command line than "--new".

It isn't necessary for the patch log of a tree to be up-to-date in
order to validate a config name, so "--accurate" to `tree-root' in
`valid-config-name' is wrong.  Also, if "--config-dir" is specified,
there's no need to call `tree-root'.

I've settled on a strict separation of argument parsing into four
sections:

	Special Options
	Ordinary Options
	Ordinary Arguments
	Sanity Check and Process Defaults

To the greatest extent practical, the first three should only set
variables, the last one should interpret those variables.  In
`valid-config-name', the last two sections are combined.  It's
probably a good idea to even put all four sections in every command,
even if the "Sanity Check" section is empty.

In an error message in something like `valid-config-name', don't say:

	config does not exist and --exists specified

say:

	config file not found

and mention the path of "$config_dir" on one of the subsequent lines.
The error message has to make sense to users of commands at a higher
level than `valid-config-name' -- they don't know anything at all
about the "--exists" option.

Print blank lines around error messages from "Sanity Check" onwards.

As a good habit, always use the "-e" flag to grep.  If someone later
alters the pattern, this helps to keep the code robust no matter what
the new pattern is.  It also helps when searching for patterns passed
to grep.

In `valid-config-name', check the validity of the config name before
the (non-)existence of the file -- it would be confusing for a user to
get a message "Hey that config already exists", then delete the file,
then get a message, "and it isn't even a valid config name!".

I changed "--config-dir" to work in the way I expected.

Don't hesitate to create long lings (160-170 characters is fine).
However, if a command has to be broken up over multiple lines, then
one option or set of closely related options per line is right.

Guidelines, not absolute rules: Indent options on continued lines.
Put the first option on the same line as the command name and align
the other arguments with the first option.  Don't try to column-align
continuation backslashes -- it's a pain in the ass to keep them that
way.

In `config-history', don't use "$archroot" as if it were "$wdroot".
It isn't.  "$archroot" is the root of a repository, not a project
tree.

